Open Spec配置基础

GitHub - Fission-AI/OpenSpec: Spec-driven development for AI coding assistants.

安装

npm install -g @fission-ai/openspec@latest

基础用法

进入项目，然后进行初始化

openspec init

接下来会以交互式的方式让你配置要使用什么CLI，然后会告诉你接下来大致该怎么做

作流程说明

阶段 1: 创建变更提案

触发条件: 新功能、破坏性变更、架构变更、性能优化、安全模式更新
工作流程:
- 选择唯一的 change-id (kebab-case, 动词开头)
- 创建目录结构: changes/[change-id]/
- 编写 proposal.md (为什么变更、变更内容、影响范围)
- 创建 tasks.md (实施检查清单)
- 如需要，创建 design.md (技术决策)
- 编写规范增量文件 specs/[capability]/spec.md
- 运行 openspec validate <id> --strict 验证

阶段 2: 实施变更

前提: 提案必须经过审查和批准
实施步骤:
- 阅读 proposal.md 理解要构建什么
- 阅读 design.md (如果存在) 了解技术决策
- 阅读 tasks.md 获取实施检查清单
- 按顺序实施任务
- 完成后更新 tasks.md 中的检查清单状态

阶段 3: 归档变更

时机: 部署完成后
操作:
- 将 changes/[name]/ 移动到 changes/archive/YYYY-MM-DD-[name]/
- 更新 specs/ 目录 (如果能力发生变化)
- 使用 openspec archive <change-id> 工具归档

关键最佳实践

规范文件格式

使用 ## ADDED|MODIFIED|REMOVED|RENAMED Requirements
每个需求必须包含至少一个 #### Scenario:
场景格式: #### Scenario: 名称 后跟 WHEN/THEN 结构

命名约定

变更 ID: kebab-case, 动词开头 (add-, update-, remove-, refactor-)
能力名称: 动词-名词 (user-auth, payment-capture)

工具使用

# 常用命令
openspec list           # 查看活动变更
openspec list --specs   # 查看现有规范
openspec show [item]    # 显示变更或规范详情
openspec validate [item]  # 验证变更或规范
openspec archive <id>   # 归档已部署的变更

我们如何协作

需求讨论: 您提出需求，我帮助分析是否需要创建变更提案
提案创建: 对于需要提案的变更，我帮助创建完整的提案文档
审查批准: 您审查提案内容，批准后开始实施
实施跟踪: 我按照 tasks.md 逐步实施，更新进度
质量保证: 确保所有变更符合项目规范和质量标准
文档更新: 完成后归档变更，更新项目文档

提交提案

讲你的想法规范化后告诉AI，明确基本的工作流

一般可以直接将下面的提示词交给AI，记得写上你需要的提案

1. 填充您的项目背景：
“请阅读 openspec/project.md 并帮我填入我的项目、技术栈和规范的详细信息”
2. 创建您的第一个变更提案：
“我想添加 [您的功能在这里]。请为此功能创建一个 OpenSpec 变更提案”
3. 了解 OpenSpec 工作流：
“请解释 openspec/AGENTS.md 中的 OpenSpec 工作流，以及我应该如何在这个项目上与您协作”

或者在对话框中使用/openspec:proposal来新增提案，比如：

/openspec:proposal 请基于curl4.md内容以及jimeng-free-api-all\src\api\controllers\images.ts 代码，新增补充基于high_aes_general_v40模型功能，请修改images.ts 实现high_aes_general_v40模型能力。
请不要先代码，先把需求整理好，结合原来的项目梳理项目新增的变革需求。

应用变更

正式开始编写代码，按照task.md中的任务一个个完成，往往消耗最多的时间

/openspec:apply

归档提案

用于方便后续AI调用之前的变更来进行决策

/openspec:archive